Quarto for the curious


Tom Mock, RStudio PBC

@thomas_mock

2022-07-27

 

We don’t talk about Quarto

We don’t talk about Quarto

A tweet by Alison Hill revealing her blogpost on Quarto. Over the weekend, I wrote up my notes about using and teaching Quarto, based on my experiences working with the development team for over a year. I think (hope?) it is safe to talk about it now

A tweet by Kelly Bodwin revealing her excitement about Quarto. Did I stay up until 6am before the first night of class converting all my R Markdown materials to @quarto_dev? Yes, yes I did. Do I regret it? No, I do not. It's pretty rad my dudes.

We don’t talk about Quarto

Others had more questions…

What is a “Quarto”?

What is a “Quarto”?1

Ok, but what IS Quarto®?

Ok, but what IS Quarto®?

Quarto® is an open-source scientific and technical publishing system built on Pandoc

How do I make a cocktail?

Image: Kobby Mendez

Crafting a cocktail

diagram of converting liquor, citrus, sugar into delicious cocktails

“Crafting” process for literate programming

“Crafting” process for literate programming

“Crafting” process for literate programming

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

diagram of converting a Jupyter notebook via pandoc into markdown and then into output formats

So what is Quarto?

A Quarto document i.e. a .qmd is a plain text file, like a .rmd, that can be rendered to many different formats

A screenshot of a Visual and Source Quarto document

Anatomy of a Quarto document

  • Metadata (YAML)
---
format: html
---
  • Code
```{r}
#| eval: true
library(dplyr)
mtcars %>% 
  group_by(cyl) %>%
  summarize(mean = mean(mpg), .groups = "drop")
```
# A tibble: 3 × 2
    cyl  mean
  <dbl> <dbl>
1     4  26.7
2     6  19.7
3     8  15.1
  • Text
# Heading 1
This is a sentence with some **bold text**, some *italic text* and an [image](image.png).

So what is Quarto?

Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into PDF/Word/HTML reports, books, websites, presentations and more!

A screenshot of a Visual and Source Quarto document

So what is Quarto?



Quarto is the next-generation of RMarkdown.

For everyone.

A brief history of knitr1

  • 2011-10-16: initial development - an engine for dynamic report generation with R

  • 2012-01-17: initial CRAN release

  • 50 CRAN releases in 10 years https://cran.r-project.org/src/contrib/Archive/knitr/

A brief history of rmarkdown

  • Initial experiment: knitr::pandoc() (2014)2

  • Matured as the rmarkdown package (2015)

Quarto - the continuation of a decade of effort

We learned from 10 years of literate programming with knitr + rmarkdown - Quarto is the continuation and unification of the best parts of RMarkdown.

diagram of converting a Quarto document via knitr/pandoc into markdown and then into output formats

Quarto - extending RMarkdown for other languages

We are meeting Julia/Python users in their native language, rather than mandating “use R” to write in their “native tongue”

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

Photo by zero take

roam in color

Comfort of your own workspace

Comfort of your own workspace

A screenshot of a Quarto document rendered inside RStudio

A screenshot of a Quarto document rendered inside JupyterLab

A screenshot of a Quarto document rendered inside VSCode

One install, batteries included

One install, “Batteries included”

  • RMarkdown grew into a large ecosystem, with varying syntax.

Quarto is a single unified install, comes “batteries included” straight out of the box

  • HTML reports and websites
  • PDF reports
  • MS Office (Word, Powerpoint)
  • Presentations (Powerpoint, Beamer, revealjs)
  • Books
  • Any language, exact same approach

Many Quarto formats

Feature R Markdown Quarto
Basic Formats
Beamer
PowerPoint
HTML Slides
Advanced Layout

Many Quarto formats

Feature R Markdown Quarto
Cross References
Websites & Blogs
Books
Interactivity Shiny Documents Quarto Interactive Documents
Paged HTML pagedown Summer 2022
Journal Articles rticles Summer 2022
Dashboards flexdashboard Fall 2022

What to do with my existing .Rmd or .ipynb?

For some of you - nothing changes! Keep using RMarkdown and Jupyter.


However, most existing .rmd or .ipynb can be rendered as-is via Quarto

quarto render my-favorite.rmd --to html


Since Jupyter notebooks can either be treated as a linear document to be re-executed or an already evaluated document there are additional options like: --execute

quarto render my-favorite.ipynb --to html --execute

Quarto comes out of the box with much better accessibility, better defaults, more options, and a much more consistent syntax.

What about for Data Science at Work?

  • Quarto can be used in RStudio Team today!
  • Quarto v1.0 comes pre-installed in RStudio Workbench 2022.07.0 and later. You can use Quarto in RStudio Workbench’s RStudio IDE, JupyterLab/Jupyter notebooks, or VSCode.
  • Quarto can be published and re-executed by RStudio Connect!

Cocktails vs Mixed Drinks

Quarto, crafted with love and care

Development of Quarto is sponsored by RStudio, PBC. The same core team works on both Quarto and R Markdown:

Here is the full contributors list. Quarto is open source and we welcome contributions in our github repository as well! https://github.com/quarto-dev/quarto-cli.

Want more?

Follow @RStudio, @quarto_pub or me @thomas_mock on Twitter to stay up to date!


rstudio::conf 2022

Web resources

The Questions

  • What does “Quarto” mean?
  • Why Quarto?
  • What about my favorite format(s)?

Why Quarto, when RMarkdown and Jupyter already exist?

  • Quarto is the “Next generation of RMarkdown”
  • but RMarkdown (and knitr) is not going away
  • And almost all the knowledge you’ve accumulated along the way is still applicable!

So let’s build up a mental model of what Quarto is and how it relates to RMarkdown and Jupyter…

rstd.io/quarto-curious by @thomas_mock